home *** CD-ROM | disk | FTP | other *** search
/ Die Speccy' 97 / Die Speccy' 97.iso / amiga_system / the_aminet / dev / gcc / ixemuldoc.lha / ixemul-bin / README.ixtrace < prev    next >
Text File  |  1995-01-14  |  4KB  |  84 lines
  1. This is an attempt at a tracer for ixemul.library. Since it scans every
  2. call made thru the library base, it catches even more calls than for
  3. example SnoopDOS.
  4.  
  5. Since tracing support slows down *all* clients of the library (as each
  6. call is now routed thru tracing functions), there are two library
  7. versions. ixemul.library itself doesn't contain tracing support, using
  8. the tracer with this library gives you a "Function not implemented"
  9. error. To use the tracer you have to load ixemul.trace as the main
  10. library. See below for more detailed instructions.
  11.  
  12.  
  13. The tracer itself is quite straight forward, a lot more calls could use
  14. more descriptive parameters, its mostly typing work, but I didn't feel
  15. like providing more ioctl, open, pipe like print functions ;-))
  16.  
  17. The option you're most certainly going to use is `-m', as the library
  18. uses sigsetmask() internally a lot, and its mentioning would just clutter
  19. the overwhole display.
  20.  
  21.  
  22. Short instructions to get the tracer up
  23. ---------------------------------------
  24. o flush ixemul.library out of the system (the WB option `FlushLibs' can
  25.   do that for you, AVAIL FLUSH achieves the same)
  26. o make sure the system loads ixemul.trace instead of ixemul.library
  27.   next time it tries to fire up ixemul.library. I usually do this by
  28.   using
  29.     LoadLib ixemul.trace
  30.   But loadlib is not an official CLI command, so you might as well
  31.   have to fiddle with libs:ixemul.library to achieve the desired effect.
  32. o Start the tracer (probably in its own window), the following options
  33.   are currently recognized (see trace.c as well):
  34.     -a    print all calls, even those considered `not interesting', for
  35.         example internal stdio calls, 32bit arithmetic emulation for 68000,
  36.         and such stuff you generally don't want to see.
  37.     -i  normally, the tracer shows a function call when that function returns,
  38.         to be able to display the return value (and `errno' in parenthesis).
  39.         When you specify `-i', it always displays function on entry, instead
  40.         of on exit. See below for current problems without the -i option!
  41.     -m  skip sigsetmask calls. This function is used extensively inside
  42.         the library, and will in most cases just clutter the tracer output
  43.         with information you don't want to see.
  44.     -o  specify a logfile. If -o is omitted, output goes to stdout.
  45.     -p  only print output from a specific process. You have to provide the
  46.         decimal address of the process (ok ok, this is not too user-friendly,
  47.         I'm open to better alternatives ;-)). Default is to scan all current
  48.         ixemul clients.
  49.     -s  only print calls to specific system call. You have to specify the
  50.         number as found in <sys/syscalls.def>. Again, this option could be
  51.         much more user-friendly, but I'm a lazy guy;-)
  52.         
  53. You should now see a log of all functions involved from your program(s), 
  54. and some functions involved as a consequence of your functions from inside
  55. the library. The output means:
  56.  
  57. $7588790: <strcmp("foo", "-n")=57 (0)
  58.   ^       ^       ^            ^   ^
  59.   |       |       |            | errno value
  60.   |       |       |          result of function
  61.   |       |     parameters
  62.   |     type of log, < means exit, > means entry
  63. process address
  64.  
  65.  
  66. Some known problems
  67. -------------------
  68. There seems to be some race condition, that can result in deadlock when
  69. running without the -i flag. I don't know, where the problem lies, such
  70. stuff is really hard to find...
  71.  
  72. Currently, if trace-on-exit is enabled, the function is called with
  73. 16 arguments, no matter how many arguments you passed to it. This should
  74. be enough for 99% of all applications, but you may have more than 16 arguments
  75. to a printf() somewhere.
  76.  
  77. Functions returning more than a 4byte result *don't* work unless you specify
  78. the -i option!!
  79.  
  80.  
  81. Happy tracing!
  82.  
  83. -Markus Wild
  84.